/**
 * Copyright 2008 Mathias Doenitz, http://lis.to/
 *
 * This file is part of the lis.to java desktop client. The lis.to java desktop client is free software: you can
 * redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option) any later version.
 *
 * The lis.to java desktop client is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with the lis.to java desktop client.
 * If not, see http://www.gnu.org/licenses/
 */

package listo.utils.reflection;

import java.lang.reflect.Field;
import java.util.List;
import java.util.Properties;
import java.util.Set;

public interface ReflectorWrapper {

    /**
     * Returns all instantiable classes in the given packages implementing or deriving from the given class or interface.
     *
     * @param packageNames the packages to search through
     * @return the classes
     */
    public List<Class> getNonAbstractImplementingClasses(String... packageNames);

    /**
     * Checks whether this type can be assigned from the given type.
     *
     * @param subType the type potentially implementing or extending this type
     * @return true if subType is, extends or implements this type
     */
    public boolean canBeCastFrom(Class subType);

    /**
     * Checks whether this type can be casted to the given type.
     *
     * @param superType the potential super type
     * @return true if this type is, extends or implements the given type
     */
    public boolean canBeCastTo(Class superType);

    /**
     * Gets ALL fields (i.e. private, proctected, public and all inherited).
     *
     * @return the list of all fields this type has
     */
    public List<Field> getAllFields();

    /**
     * Gets the field (public, protected or private, also inherited) with the given name.
     *
     * @param fieldName the name of the field
     * @return the field
     */
    public Field getField(String fieldName);

    /**
     * Gets the value of the field (public, protected or private, also inherited) with
     * the given name.
     *
     * @param fieldName the name of the field
     * @return the value of the field
     */
    public Object getFieldValue(String fieldName);

    /**
     * Sets the value of the field (public, protected or private, also inherited) with
     * the given name.
     *
     * @param fieldName the name of the field
     * @param value     the value of the field
     */
    public void setFieldValue(String fieldName, Object value);

    /**
     * Gets the value of the property (public, protected or private, also inherited) with
     * the given name.
     *
     * @param propertyName the name of the property
     * @return the value of the field
     */
    public Object getPropertyValue(String propertyName);

    /**
     * Sets the value of the property (public, protected or private, also inherited) with
     * the given name.
     *
     * @param propertyName the name of the field
     * @param value        the value of the field
     */
    public void setPropertyValue(String propertyName, Object value);

    /**
     * Returns the set of all super types (classes and interfaces) of this type.
     * This type itself is also included.
     *
     * @return the set
     */
    public Set<Class> getAllSuperTypes();

    /**
     * Find the best matching handler class for the object/class based on the given name pattern.
     *
     * @param namePattern the class name pattern to base the search on
     * @return the class
     */
    public Class getHandlerClass(String namePattern);

    /**
     * Perfoms a depth-first tree walk of this objects object graph starting with this object.
     * Circular references are ignored (i.e. only processed on the first occurrence).
     *
     * @param action the action to perform on each object
     * @param types  an optional list of types to limit the action to
     */
    public void traverseObjectTree(ObjectTreeWalkAction action, Class... types);

    /**
     * Fills all fields of the object with the from String values from the given properties.
     *
     * @param properties the properties
     */
    public void loadFromProperties(Properties properties);

    /**
     * Creates a Properties object filled with all fieldnames (keys) and their toString values (values).
     *
     * @return the generated Properties
     */
    public Properties saveToProperties();

    /**
     * Creates a Properties object filled with all fieldnames (keys) and their toString values (values).
     *
     * @param includeFinalFields set to false to ignore final fields
     * @return the generated Properties
     */
    public Properties saveToProperties(boolean includeFinalFields);

}
